Strip spec references and process labels from docstrings#169
Merged
Conversation
Remove opaque development-history tags (PR-C, PR-B, Phase 6.0/6.1) and rephrase the "Phase N scope/deferred" mentions to preserve their covered-vs-deferred meaning without the process vocabulary. Rename the langfuse resume test's internal "Phase 1/2/3" step labels to "Step" to avoid confusion with build phases. Leaves the harness skip registry untouched: its DIRECTIVE_PHASE dict maps directives to phase integers as functional data, and its comments document that live mapping. Fixture-number references are kept throughout (concrete in-repo identifiers, not spec refs).
There was a problem hiding this comment.
Pull request overview
This PR performs documentation-only cleanup across src/ and tests/, aiming to remove spec-section/proposal/process-history references from docstrings and rephrase them as descriptive prose (with any spec rationale moved to # comments).
Changes:
- Rewrites many docstrings to remove section/proposal/version/process labels.
- Adjusts nearby comments to carry spec rationale where needed.
- Updates conformance harness/test prose to remove “Phase/PR-*” process vocabulary.
Reviewed changes
Copilot reviewed 64 out of 64 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/test_tool_choice.py | Docstring wording cleanup around tool_choice tests. |
| tests/unit/test_state_migration.py | Docstring wording cleanup for migration registry tests. |
| tests/unit/test_runtime_errors.py | Docstring wording cleanup for runtime error category tests. |
| tests/unit/test_projection.py | Docstring wording cleanup for projection behavior tests. |
| tests/unit/test_parallel_branches.py | Docstring wording cleanup for parallel-branches tests. |
| tests/unit/test_observer.py | Docstring wording cleanup for observer queue tests. |
| tests/unit/test_observability_otel.py | Docstring/comment wording cleanup for OTel observer tests. |
| tests/unit/test_observability_metadata.py | Docstring wording cleanup for invocation metadata tests. |
| tests/unit/test_middleware.py | Docstring/comment wording cleanup for middleware tests. |
| tests/unit/test_llm_provider.py | Docstring wording cleanup for provider behavior tests. |
| tests/unit/test_fan_out.py | Docstring wording cleanup for fan-out runtime tests. |
| tests/unit/test_failure_isolation_middleware.py | Docstring wording cleanup for failure isolation middleware tests. |
| tests/unit/test_drain.py | Docstring wording cleanup for drain() tests. |
| tests/unit/test_correlation.py | Docstring/comment wording cleanup for correlation primitives tests. |
| tests/unit/test_compile_errors.py | Docstring wording cleanup for compile error tests. |
| tests/unit/test_checkpoint.py | Docstring/comment wording cleanup for checkpoint tests. |
| tests/integration/test_langfuse_sdk_adapter.py | Comment wording cleanup around adapter migration failure mode. |
| tests/conformance/test_state_migration.py | Docstring/comment wording cleanup for state migration conformance runner. |
| tests/conformance/test_prompt_management.py | Docstring wording cleanup for prompt-management conformance helpers. |
| tests/conformance/test_pipeline_utilities.py | Docstring/comment wording cleanup for pipeline-utilities conformance driver. |
| tests/conformance/test_observability.py | Docstring/comment wording cleanup for observability conformance runner. |
| tests/conformance/test_observability_langfuse.py | Comment wording cleanup replacing phase vocabulary with step vocabulary. |
| tests/conformance/test_llm_provider.py | Docstring wording cleanup for LLM provider conformance runner. |
| tests/conformance/test_fixture_parsing.py | Docstring wording cleanup for fixture parsing tests. |
| tests/conformance/test_conformance.py | Comment wording cleanup for adapter unsupported directives note. |
| tests/conformance/test_checkpoint.py | Docstring/comment wording cleanup for checkpoint conformance runner. |
| tests/conformance/middleware_seam.py | Docstring wording cleanup for middleware seam helpers. |
| tests/conformance/harness/wire.py | Docstring wording cleanup for wire assertion helpers. |
| tests/conformance/harness/llm_attribute_assertions.py | Docstring wording cleanup for LLM attribute assertion helpers. |
| tests/conformance/harness/fixtures.py | Docstring wording cleanup for typed fixture models. |
| tests/conformance/harness/expectations.py | Docstring wording cleanup for expectations models. |
| tests/conformance/harness/directives.py | Docstring/comment wording cleanup for directive models. |
| tests/conformance/harness/init.py | Docstring wording cleanup for harness module overview. |
| tests/conformance/adapter.py | Docstring/comment wording cleanup for conformance adapter helpers. |
| src/openarmature/prompts/prompt.py | Module/class docstring cleanup; spec rationale moved to comments. |
| src/openarmature/prompts/manager.py | Docstring cleanup for PromptManager behavior descriptions. |
| src/openarmature/prompts/label_resolver.py | Docstring cleanup for label resolver contract. |
| src/openarmature/prompts/hashing.py | Docstring cleanup for hashing function description. |
| src/openarmature/prompts/errors.py | Docstring cleanup for prompt error descriptions. |
| src/openarmature/prompts/context.py | Docstring cleanup for prompt context propagation notes. |
| src/openarmature/prompts/backends/langfuse.py | Module docstring/comment cleanup for Langfuse backend. |
| src/openarmature/prompts/backends/filesystem.py | Docstring cleanup for filesystem backend behavior. |
| src/openarmature/observability/otel/observer.py | Docstring/comment cleanup for OTel observer implementation notes. |
| src/openarmature/observability/metadata.py | Docstring/comment cleanup for invocation metadata contract. |
| src/openarmature/observability/langfuse/observer.py | Docstring/comment cleanup for Langfuse observer implementation notes. |
| src/openarmature/observability/langfuse/client.py | Docstring/comment cleanup for Langfuse client protocol and models. |
| src/openarmature/observability/langfuse/init.py | Docstring wording cleanup for Langfuse observability package. |
| src/openarmature/observability/correlation.py | Docstring/comment cleanup for invocation_id validation and hooks. |
| src/openarmature/llm/providers/openai.py | Docstring/comment cleanup for OpenAI provider mapping notes. |
| src/openarmature/llm/provider.py | Docstring cleanup for provider protocol + tool_choice validation. |
| src/openarmature/llm/messages.py | Docstring cleanup for ForceTool semantics. |
| src/openarmature/graph/parallel_branches.py | Module/class docstring cleanup; spec rationale moved to comments. |
| src/openarmature/graph/observer.py | Docstring/comment cleanup for observer queue/drain structures. |
| src/openarmature/graph/middleware/_core.py | Comment wording cleanup around middleware chain performance note. |
| src/openarmature/graph/fan_out.py | Docstring/comment cleanup for fan-out runtime semantics. |
| src/openarmature/graph/events.py | Docstring/comment cleanup for event model docs. |
| src/openarmature/graph/errors.py | Docstring cleanup for parallel-branches errors. |
| src/openarmature/graph/compiled.py | Docstring/comment cleanup for compiled graph internals. |
| src/openarmature/graph/builder.py | Docstring cleanup for builder APIs. |
| src/openarmature/checkpoint/protocol.py | Module/docstring cleanup for checkpoint protocol types. |
| src/openarmature/checkpoint/migration.py | Module/docstring cleanup for migration registry types. |
| src/openarmature/checkpoint/errors.py | Docstring cleanup for checkpoint error types. |
| src/openarmature/checkpoint/backends/sqlite.py | Docstring cleanup for sqlite save() description. |
| src/openarmature/checkpoint/backends/memory.py | Docstring/comment cleanup for in-memory backend batching semantics. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The first sweep stripped structured spec references (section markers,
proposal numbers, versions) but left prose that still cited the spec
as the authority for a rule ("The spec defines/permits/mandates",
"spec-mandated", "spec-normative", "per spec"). State the behavior
directly, or move the basis to a nearby comment where load-bearing.
Structural mentions are kept: the spec/ conformance directories, the
spec parameter in the harness, spec-version reads, and descriptions of
what the conformance suite covers.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two related documentation cleanups across
src/andtests/, no code or behavior changes.1. Spec references out of docstrings. Docstrings no longer carry spec section markers (
§4.2), proposal numbers, version pins, or prose that cites the spec as the authority for a rule ("The spec defines/permits/mandates", "spec-mandated", "per spec"). Each now reads as plain descriptive prose; where the spec basis was load-bearing it moved to a nearby#comment, otherwise it was dropped. This follows the convention that docstrings document behavior and#comments carry spec rationale.2. Process labels out of docstrings and comments. Opaque development-history tags (
PR-C,PR-B,Phase 6.0/6.1) are removed, and the "Phase N scope/deferred" mentions are rephrased to keep their covered-vs-deferred meaning without the process vocabulary.Deliberately kept
fixture 048,fixtures 058-063): concrete in-repo identifiers pointing at conformance fixtures, not spec references.spec/conformance directories andopenarmature-specsubmodule, thespecparameter in the harness, spec-version reads, and descriptions of what the conformance suite exercises ("covers the spec's behavioral surface"). These name real artifacts rather than citing the spec as authority.tests/conformance/harness/skip.py): itsDIRECTIVE_PHASEdict maps directives to phase integers as functional data, and its comments document that live mapping.Verification
No spec section/proposal/version references and no spec-authority citations remain in docstrings; full suite green (1321 passed). Commits are split per area for review.